---
id: radio-group
title: Radio Group
description: Allows single selection from multiple options.
---

<ComponentPreview id="RadioGroup" />

## Anatomy

To set up the radio group correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="radio-group" />

## Examples

Learn how to use the `RadioGroup` component in your project. Let's take a look at the most basic example:

<Example id="basic" />

### Disabling the radio group

To make a radio group disabled, set the `disabled` prop to `true`.

<Example id="disabled" />

### Setting the initial value

To set the radio group's initial value, set the `defaultValue` prop to the value of the radio item to be selected by
default.

<Example id="initial-value" />

### Listening for changes

When the radio group value changes, the `onValueChange` callback is invoked.

<Example id="on-event" />

### Using the Root Provider

The `RootProvider` component provides a context for the radio-group. It accepts the value of the `useRadio-group` hook.
You can leverage it to access the component state and methods from outside the radio-group.

<Example id="root-provider" />

> If you're using the `RootProvider` component, you don't need to use the `Root` component.

## Guides

### Using `asChild`

The `RadioGroup.Item` component renders as a `label` element by default. This ensures proper form semantics and
accessibility, as radio groups are form controls that require labels to provide meaningful context for users.

When using the `asChild` prop, you must **render a `label` element** as the direct child of `RadioGroup.Item` to
maintain valid HTML structure and accessibility compliance.

```tsx
// INCORRECT usage ❌
<RadioGroup.Item asChild>
  <div>
    <RadioGroup.ItemHiddenInput />
    <RadioGroup.ItemText>
      <RadioGroup.ItemControl />
    </RadioGroup.ItemText>
  </div>
</RadioGroup.Item>

// CORRECT usage ✅
<RadioGroup.Item asChild>
  <label>
    <RadioGroup.ItemHiddenInput />
    <RadioGroup.ItemText>
      <RadioGroup.ItemControl />
    </RadioGroup.ItemText>
  </label>
</RadioGroup.Item>
```

### Why `ItemHiddenInput` is required

The `RadioGroup.ItemHiddenInput` component renders a hidden HTML input element that enables proper form submission and
integration with native form behaviors. This component is essential for the radio group to function correctly as it:

- Provides the underlying input element that browsers use for form submission
- Enables integration with form libraries and validation systems
- Ensures the radio group works with native form reset functionality

```tsx
// INCORRECT usage ❌
<RadioGroup.Item>
  <RadioGroup.ItemText>
    <RadioGroup.ItemControl />
  </RadioGroup.ItemText>
</RadioGroup.Item>

// CORRECT usage ✅
<RadioGroup.Item>
  <RadioGroup.ItemHiddenInput />
  <RadioGroup.ItemText>
    <RadioGroup.ItemControl />
  </RadioGroup.ItemText>
</RadioGroup.Item>
```

## API Reference

### Props

<ComponentTypes id="radio-group" />

### Context

These are the properties available when using `RadioGroup.Context`, `useRadioGroupContext` hook or `useRadioGroup` hook.

<ContextType id="radio-group" />

## Accessibility

Complies with the [Radio WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).

### Keyboard Support

<KeyBindingsTable id="radio-group" />
